import Details from '@/components/Details';

# Core library

While `next-intl` is primarily intended to be used in Next.js apps, the core is agnostic and can be used independently—either in React apps or any other JavaScript environment.

## React apps

`next-intl` internally uses a library called [`use-intl`](https://www.npmjs.com/package/use-intl). This core library contains most features you're familiar with from `next-intl`, but lacks the following Next.js-specific features:

1. [Routing APIs](/docs/routing)
2. [Awaitable APIs](/docs/environments/actions-metadata-route-handlers) for Server Actions, Metadata and Route Handlers
3. [Server Components integration](/docs/environments/server-client-components) along with `i18n/request.ts`

In case Server Components establish themselves in React apps outside of Next.js, the support for Server Components might be moved to the core library in the future.

In contrast, `use-intl` contains all APIs that are necessary for handling i18n in regular React apps:

- [`useTranslations`](/docs/usage/translations) for translating messages
- `useFormatter` for formatting [numbers](/docs/usage/numbers), [dates & times](/docs/usage/dates-times) and [lists](/docs/usage/lists)
- [Configuration APIs](/docs/usage/configuration) (note however that `NextIntlProvider` is called `IntlProvider` in `use-intl`)

This allows you to use the same APIs that you know from `next-intl` in other environments:

1. React Apps ([example](/examples#use-intl))
2. React Native ([example](/examples#react-native))
3. Remix ([example](/examples#remix))
4. Testing environments like Jest ([example](https://github.com/amannn/next-intl/blob/main/examples/example-app-router/src/components/Navigation.spec.tsx))
5. [Storybook](/docs/workflows/storybook)

**Basic usage:**

```tsx
import {IntlProvider, useTranslations} from 'use-intl';

// You can get the messages from anywhere you like. You can also
// fetch them from within a component and then render the provider
// along with your app once you have the messages.
const messages = {
  App: {
    hello: 'Hello {username}!'
  }
};

function Root() {
  return (
    <IntlProvider messages={messages} locale="en">
      <App user={{name: 'Jane'}} />
    </IntlProvider>
  );
}

function App({user}) {
  const t = useTranslations('App');
  return <h1>{t('hello', {username: user.name})}</h1>;
}
```

<Details id="shared-components">
<summary>Can I build shared components that work in both Next.js and plain React apps?</summary>

Yes, shared components that render in either environment are supported.

In this case, it can be beneficial to import from `next-intl` for the relevant components, to be able to benefit from the [Server
Components integration](/docs/environments/server-client-components) in case you render them in Next.js. In other environments, imports to `next-intl` will work as well, but will require `IntlProvider` to be present.

</Details>

## Non-React apps

Besides the React-specific APIs, `use-intl` also exports two low-level functions that can be used in any JavaScript environment:

1. `createTranslator` for translating messages
2. `createFormatter` for formatting numbers, dates & times and lists

These APIs receive all relevant configuration directly and don't rely on global configuration.

You can use these APIs as follows:

```tsx
import {createTranslator, createFormatter} from 'use-intl/core';

const messages = {
  basic: 'Hello {name}!',
  rich: 'Hello <b>{name}</b>!'
};

// This creates the same function that is returned by `useTranslations`.
// Since there's no provider, you can pass all the properties you'd
// usually pass to the provider directly here.
const t = createTranslator({locale: 'en', messages});

// Result: "Hello world!"
t('basic', {name: 'world'});

// To generate HTML markup, you can consider using the `markup`
// function which in contrast to `t.rich` returns a markup string.
t.markup('rich', {
  name: 'world',
  b: (chunks) => `<b>${chunks}</b>`
});

// Creates the same object that is returned by `useFormatter`.
const format = createFormatter({locale: 'en'});

// Result: "Oct 17, 2022"
format.dateTime(new Date(2022, 9, 17), {dateStyle: 'medium'});
```
